---
title: "Filter API"
---

You can access and set the models for filters through the grid API, or access individual filter instances directly for more control. This page details how to do both.

{% note %}
The filter model can be saved and restored as part of [Grid State](./grid-state/).
{% /note %}

## Get / Set All Filter Models

It is possible to get the state of all filters using the grid API method `getFilterModel()`, and to set the state using
`setFilterModel()`. These methods manage the filters states via the `getModel()` and `setModel()` methods of the
individual filters.

{% apiDocumentation source="grid-api/api.json" section="filter" names=["getFilterModel", "setFilterModel"] /%}

```{% frameworkTransform=true %}
// Gets filter model via the grid API
const model = api.getFilterModel();

// Sets the filter model via the grid API
api.setFilterModel(model);
```

The filter model represents the state of filters for all columns and has the following structure:

```js
// Sample filter model via getFilterModel()
{
    athlete: {
        filterType: 'text',
        type: 'startsWith',
        filter: 'mich'
    },
    age: {
        filterType: 'number',
        type: 'lessThan',
        filter: 30
    }
}
```

This is useful if you want to save the global filter state and apply it at a later stage. It is also useful for server-side filtering, where you want to pass the filter state to the server.

### Reset All Filters

You can reset all filters by doing the following:

```{% frameworkTransform=true %}
api.setFilterModel(null);
```

### Example: Get / Set All Filter Models

The example below shows getting and setting all the filter models in action.

* `Save Filter Model` saves the current filter state, which will then be displayed.
* `Restore Saved Filter Model` restores the saved filter state back into the grid.
* `Set Custom Filter Model` takes a custom hard-coded filter model and applies it to the grid.
* `Reset Filters` will clear all active filters.
* `Destroy Filter` destroys the filter for the **Athlete** column by calling `gridApi.destroyFilter('athlete')`. This removes any active filter from that column, and will cause the filter to be created with new initialisation values the next time it is interacted with.

(Note: the example uses the Enterprise-only [Set Filter](./filter-set/)).

{% gridExampleRunner title="Filter Model" name="filter-model"  exampleHeight=587 /%}

## Get / Set Individual Filter Model

It is also possible to get or set the filter model for a specific filter, including your own custom filters.

{% apiDocumentation source="grid-api/api.json" section="filter" names=["getColumnFilterModel", "setColumnFilterModel"] /%}

### Re-running Grid Filtering

After filters have been changed via their API, you must ensure the method `gridApi.onFilterChanged()` is called to tell the grid to filter the rows again. If `gridApi.onFilterChanged()` is not called, the grid will still show the data relevant to the filters before they were updated through the API.

```js
// Set a filter model
await api.setColumnFilterModel('name', {
    filterType: 'text',
    type: 'startsWith',
    filter: 'abc',
});

// Tell grid to run filter operation again
api.onFilterChanged();
```

### Reset Individual Filters

You can reset a filter to its original state by setting the model to `null`.

```js
// Set the model to null
await api.setColumnFilterModel('name', null);

// Tell grid to run filter operation again
api.onFilterChanged();
```

### Example: Get / Set Individual Filter Model

The example below shows getting and setting an individual filter model in action.

* `Save Filter Model` saves the **Athlete** filter state, which will then be displayed.
* `Restore Saved Filter Model` restores the saved **Athlete** filter state back into the grid.
* `Set Custom Filter Model` takes a custom hard-coded **Athlete** filter model and applies it to the grid.
* `Reset Filter` will clear the **Athlete** filter.

{% gridExampleRunner title="Individual Filter Model" name="filter-model-individual"  exampleHeight=587 /%}

## Accessing Individual Filters

It certain cases, it may be needed to interact directly with a specific filter. For instance, [Refreshing Values](./filter-set-filter-list/#refreshing-values) on the Set Filter.

Grid-provided filters are split into two parts - the filter UI component and the filter handler (which performs the filter logic).

When `enableFilterHandlers = true`, [Custom Filter Components](./component-filter/) are also split into two parts.

Note that the [Multi Filter](./filter-multi/) will only have a filter handler when `enableFilterHandlers = true`.

To access the filter UI component, use `api.getColumnFilterInstance(colKey)`.

To access the filter hander, use `api.getColumnFilterHandler(colKey)`.

{% apiDocumentation source="grid-api/api.json" section="filter" names=["getColumnFilterInstance", "getColumnFilterHandler"] /%}

```js
// Get a reference to the 'name' filter UI instance
const filterInstance = await api.getColumnFilterInstance('name');
```

If using a custom filter, any other methods you have added will also be present, allowing bespoke behaviour to be added to your filter.

### Example: Accessing Individual Filters

The example below shows how you can interact with an individual filter instance, using the Set Filter as an example.

* `Get Mini Filter Text` will print the text from the Set Filter's Mini Filter to the console.
* `Save Mini Filter Text` will save the Mini Filter text.
* `Restore Mini Filter Text` will restore the Mini Filter text from the saved state.

(Note: the example uses the Enterprise-only [Set Filter](./filter-set/)).

{% gridExampleRunner title="Accessing Individual Filters" name="filter-api"  exampleHeight=624 /%}

## Read-only Filter UI

Sometimes it maybe useful to strictly control the filters used by the grid via API, whilst still exposing filter settings in-use to users. The `readOnly` filter parameter changes the behaviour of all provided column filters so their UI is read-only. In this mode, API filter changes are still honoured and reflected in the UI:

```{% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        {
            field: 'age',
            filter: true,
            filterParams: {
                readOnly: true
            }
        }
    ]
}
```

The following example demonstrates all of the Provided Filters with `readOnly: true` enabled:

* Simple Filters have a read-only display with no buttons; if there is no 2nd condition set then the join operator and 2nd condition are hidden:
  * `athlete` column demonstrates [Text Filter](./filter-text/).
  * `age` and `year` columns demonstrate [Number Filter](./filter-number/).
  * `date` column demonstrates [Date Filter](./filter-date/).
* [Set Filter](./filter-set/) allows Mini Filter searching of values, but value inclusion/exclusion cannot be toggled; buttons are also hidden, and pressing enter in the Mini Filter input has no effect:
  * `country`, `gold`, `silver` and `bronze` columns demonstrate [Set Filter](./filter-set/).
* [Multi Filter](./filter-multi/) has no direct behaviour change, sub-filters need to be individually made read-only. `readOnly: true` is needed to affect any associated [Floating Filters](./floating-filters/).
  * `sport` column demonstrates [Multi Filter](./filter-multi/).
* [Floating Filters](./floating-filters/) are enabled and inherit `readOnly: true` from their parent, disabling any UI input.
* Buttons above the grid provide API interactions to configure the filters.
* `Print Country` button prints the country model to the developer console.

{% gridExampleRunner title="Read-only Filter UI" name="filter-api-readonly"  exampleHeight=624 /%}

## Launching Filters

How filters are launched can be customised (unless grid option `columnMenu = 'legacy'`).

`colDef.suppressHeaderFilterButton = true` can be used to disable the button in the header that opens the filter.

The filter can also be launched via `api.showColumnFilter(columnKey)` and hidden via `api.hideColumnFilter()`.

The following example demonstrates launching the filter:

* The **Athlete** column has a filter button in the header to launch the filter.
* The **Age** column has a floating filter, so the header button is automatically hidden.
* The **Country** column has the filter button hidden via `colDef.suppressHeaderFilterButton`. The filter can still be opened via the API by clicking the `Open Country Filter` button.
* The **Year** column has a floating filter and the header button is also suppressed, so has a slightly different display style when the filter is active.

{% gridExampleRunner title="Launching Filters" name="launching-filters" /%}

## Filter Events

Filtering causes the following events to be emitted:

{% apiDocumentation source="grid-events/events.json" section="filter" names=["filterOpened", "filterChanged", "filterModified", "filterUiChanged", "floatingFilterUiChanged"] /%}

## Next Up

Continue to the next section to learn about [Custom Column Filters](./component-filter/).
